Skip to content

feat(core): 支持 ISV 子商户身份头 x-wop-sub-mch-id 入签 - #45

Merged
im47cn merged 4 commits into
wop-platform:mainfrom
txiao8586:main
Oct 28, 2026
Merged

im47cn merged 4 commits into
wop-platform:mainfrom
txiao8586:main

Conversation

@txiao8586

@txiao8586 txiao8586 commented Oct 28, 2026 •

Copy link
Copy Markdown

ISV D-13:build_request/execute 新增 sub_mch_id,签名前写入 x-wop-sub-mch-id 并自动纳入 signedHeaders;不传/空白 = 应用自身身份,头缺席,头集合与签名与旧版逐字节一致(AC-20)。extra_headers 携带该头等价参数,双来源同传即拒。校验:可打印 ASCII、无内部空白、trim 后 ≤128 字符。补 test_submchid.py。

What does this PR do?

Spec compliance

Checklist

  • Tests updated and passing locally with the repository's own CI commands
  • No modification to golden test vectors (crypto-vectors.json is read-only)
  • Conventional Commits format used

Sourcery 摘要

支持在请求构造和执行过程中使用已签名的 ISV 子商户身份,同时默认保留旧版签名行为。

新功能:

  • 通过 sub_mch_id 参数和已签名的 x-wop-sub-mch-id 请求头,支持为每个请求指定 ISV 子商户身份。

增强功能:

  • 未提供子商户身份或其值为空时,保留与旧版逐字节一致的请求;同时验证并规范化提供的身份,并拒绝来源冲突的情况。

文档:

  • 在英文和中文 README 文件中说明 ISV 子商户身份的用法、验证规则、签名行为和启用要求。

测试:

  • 增加对已签名子商户请求头、等效的额外请求头输入、来源冲突、验证边界以及旧版行为回归的测试覆盖。
Original summary in English

Sourcery 摘要

新增对已签名的 ISV 子商户身份的支持,同时默认保留现有的请求签名行为。

新功能:

  • 支持在构造和执行请求时,通过已签名的 x-wop-sub-mch-id 请求头指定该请求的 ISV 子商户身份。

增强:

  • 当未提供子商户身份或该身份为空白时,逐字节保留旧版请求头和签名;同时对提供的身份进行验证和规范化,并拒绝相互冲突的输入。

文档:

  • 在英文和中文 README 文件中说明 ISV 子商户身份的用法、验证规则、签名行为和启用要求。

测试:

  • 新增测试,覆盖已签名的子商户请求头、等效的额外请求头输入、来源冲突、验证边界、执行时的传递,以及旧版行为回归。
Original summary in English

Sourcery 总结

新增对已签名 ISV 子商户身份的支持,同时默认保留现有的请求签名行为。

新功能:

  • 支持在构造和执行请求时,通过已签名的 x-wop-sub-mch-id 请求头为每个请求指定 ISV 子商户身份。

改进:

  • 未提供子商户身份或其值为空白时,保留与旧版逐字节一致的请求头和签名;对提供的值进行校验和规范化,并拒绝相互冲突的来源。

CI:

  • 在 CI 中固定 pytest 和 pytest-bdd 的版本,以保持与测试套件的兼容性。

文档:

  • 在英文和中文 README 中说明 ISV 子商户身份的用法、校验规则、签名行为及网关前置条件。

测试:

  • 增加对已签名子商户请求头、等效的额外请求头输入、来源冲突、校验边界、执行时的传递,以及旧版行为回归的覆盖。
Original summary in English

Summary by Sourcery

Add signed ISV sub-merchant identity support while preserving existing request signing behavior by default.

New Features:

  • Support specifying an ISV sub-merchant identity per request through the signed x-wop-sub-mch-id header in both request construction and execution.

Enhancements:

  • Preserve byte-for-byte legacy headers and signatures when the sub-merchant identity is omitted or blank, while validating and normalizing supplied values and rejecting conflicting sources.

CI:

  • Pin pytest and pytest-bdd versions in CI to maintain compatibility with the test suite.

Documentation:

  • Document ISV sub-merchant identity usage, validation rules, signing behavior, and gateway prerequisites in English and Chinese READMEs.

Tests:

  • Add coverage for signed sub-merchant headers, equivalent extra-header input, source conflicts, validation boundaries, execution propagation, and legacy behavior regression.

ISV D-13:build_request/execute 新增 sub_mch_id,签名前写入 x-wop-sub-mch-id 并自动纳入 signedHeaders;不传/空白 = 应用自身身份,头缺席,头集合与签名与旧版逐字节一致(AC-20)。extra_headers 携带该头等价参数,双来源同传即拒。校验:可打印 ASCII、无内部空白、trim 后 ≤128 字符。补 test_submchid.py。

Co-Authored-By: Claude Code <noreply@anthropic.com>
@txiao8586
txiao8586 requested a review from im47cn as a code owner October 28, 2026 05:09
@changeset-bot

changeset-bot Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 28760a0

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@coderabbitai

coderabbitai Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 58600cd6-9f01-4002-b26b-31668bc88995
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sourcery-ai

sourcery-ai Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

评审者指南

该 PR 实现 ISV D-13 子商户身份支持:在请求签名前解析并校验 sub_mch_id,注入 x-wop-sub-mch-id 并纳入签名;同时支持等价的 extra_headers 来源、拒绝歧义输入,并通过文档和测试保障空值场景的 AC-20 向后兼容。

ISV 子商户请求签名时序图

sequenceDiagram
    participant Caller
    participant Client
    participant Signer
    participant Gateway
    Caller->>Client: build_request or execute with sub_mch_id
    Client->>Client: resolve_sub_mch_id
    alt valid non-blank sub_mch_id
        Client->>Client: add x-wop-sub-mch-id
        Client->>Signer: sign headers including x-wop-sub-mch-id
        Signer-->>Client: x-wop-sign
    else blank or omitted
        Client->>Signer: sign legacy header set
        Signer-->>Client: x-wop-sign
    end
    Client->>Gateway: send signed request
Loading

子商户身份输入解析流程图

flowchart TD
    A[Receive sub_mch_id or extra_headers] --> B{Both sources provided?}
    B -- Yes --> C[Raise ConfigurationError]
    B -- No --> D[resolve_sub_mch_id]
    D --> E{Printable ASCII, no internal whitespace, length <= 128?}
    E -- No --> C
    E -- Blank after trim --> F[Omit x-wop-sub-mch-id]
    E -- Valid --> G[Add x-wop-sub-mch-id before signing]
    F --> H[Sign legacy header set]
    G --> I[Include header in signedHeaders]
Loading

文件级变更

变更 详情 文件
新增 ISV 子商户身份参数解析、校验及签名头注入流程。
  • 增加 sub_mch_id 请求参数并贯穿 build_request 与 execute。
  • 将参数或 extra_headers 中的 x-wop-sub-mch-id 统一解析,trim 后写入请求头并自动加入 signedHeaders。
  • 拒绝双来源同时提供,并校验可打印 ASCII、无内部空白及 128 字符长度限制。
  • 空值或纯空白不产生请求头,保持旧版请求头集合和签名字节级兼容。
src/wop_sdk/client.py
补充 ISV D-13 的行为、兼容性和使用说明。
  • 记录参数用法、签名行为、输入约束及灰度/ISV 生效条件。
README.md
README.en.md
增加子商户身份头的签名、来源冲突、校验和 AC-20 回归测试。
  • 验证不同请求级别和请求体下头部进入 signedHeaders 且签名可验。
  • 覆盖参数与 extra header 等价、双来源拒绝、trim、非法字符、内部空白和长度边界。
  • 确认未传或传空白时与基线请求完全一致。
tests/test_submchid.py

提示与命令

与 Sourcery 交互

  • 触发新的评审: 在拉取请求中评论 @sourcery-ai review。
  • 继续讨论: 直接回复 Sourcery 的评审评论。
  • 根据评审评论创建 GitHub issue: 回复评审评论,请 Sourcery 根据该评论创建 issue。你也可以在评审评论中回复 @sourcery-ai issue 来创建 issue。
  • 生成拉取请求标题: 在拉取请求标题的任意位置写入 @sourcery-ai,即可随时生成标题。你也可以在拉取请求中评论 @sourcery-ai title,随时重新生成标题。
  • 生成拉取请求摘要: 在拉取请求正文中需要生成摘要的位置写入 @sourcery-ai summary,即可随时在指定位置生成 PR 摘要。你也可以在拉取请求中评论 @sourcery-ai summary,随时重新生成摘要。
  • 生成评审者指南: 在拉取请求中评论 @sourcery-ai guide,即可随时重新生成评审者指南。
  • 解决所有 Sourcery 评论: 在拉取请求中评论 @sourcery-ai resolve,即可解决所有 Sourcery 评论。如果你已处理完所有评论且不想再看到它们,这个命令会很有用。
  • 驳回所有 Sourcery 评审: 在拉取请求中评论 @sourcery-ai dismiss,即可驳回所有现有的 Sourcery 评审。如果你想从头开始进行新的评审,这个命令尤其有用——别忘了评论 @sourcery-ai review 来触发新的评审!

自定义使用体验

访问你的控制面板,以便:

  • 启用或停用评审功能,例如 Sourcery 生成的拉取请求摘要、评审者指南等。
  • 更改评审语言。
  • 添加、移除或编辑自定义评审说明。
  • 调整其他评审设置。

获取帮助

Original review guide in English

Reviewer's Guide

该 PR 实现 ISV D-13 子商户身份支持:在请求签名前解析并校验 sub_mch_id,注入 x-wop-sub-mch-id 并纳入签名;同时支持等价的 extra_headers 来源、拒绝歧义输入,并通过文档和测试保障空值场景的 AC-20 向后兼容。

Sequence diagram for ISV sub-merchant request signing

sequenceDiagram
    participant Caller
    participant Client
    participant Signer
    participant Gateway
    Caller->>Client: build_request or execute with sub_mch_id
    Client->>Client: resolve_sub_mch_id
    alt valid non-blank sub_mch_id
        Client->>Client: add x-wop-sub-mch-id
        Client->>Signer: sign headers including x-wop-sub-mch-id
        Signer-->>Client: x-wop-sign
    else blank or omitted
        Client->>Signer: sign legacy header set
        Signer-->>Client: x-wop-sign
    end
    Client->>Gateway: send signed request
Loading

Flow diagram for sub-merchant identity input resolution

flowchart TD
    A[Receive sub_mch_id or extra_headers] --> B{Both sources provided?}
    B -- Yes --> C[Raise ConfigurationError]
    B -- No --> D[resolve_sub_mch_id]
    D --> E{Printable ASCII, no internal whitespace, length <= 128?}
    E -- No --> C
    E -- Blank after trim --> F[Omit x-wop-sub-mch-id]
    E -- Valid --> G[Add x-wop-sub-mch-id before signing]
    F --> H[Sign legacy header set]
    G --> I[Include header in signedHeaders]
Loading

File-Level Changes

Change Details Files
新增 ISV 子商户身份参数解析、校验及签名头注入流程。
  • 增加 sub_mch_id 请求参数并贯穿 build_request 与 execute。
  • 将参数或 extra_headers 中的 x-wop-sub-mch-id 统一解析,trim 后写入请求头并自动加入 signedHeaders。
  • 拒绝双来源同时提供,并校验可打印 ASCII、无内部空白及 128 字符长度限制。
  • 空值或纯空白不产生请求头,保持旧版请求头集合和签名字节级兼容。
src/wop_sdk/client.py
补充 ISV D-13 的行为、兼容性和使用说明。
  • 记录参数用法、签名行为、输入约束及灰度/ISV 生效条件。
README.md
README.en.md
增加子商户身份头的签名、来源冲突、校验和 AC-20 回归测试。
  • 验证不同请求级别和请求体下头部进入 signedHeaders 且签名可验。
  • 覆盖参数与 extra header 等价、双来源拒绝、trim、非法字符、内部空白和长度边界。
  • 确认未传或传空白时与基线请求完全一致。
tests/test_submchid.py

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

嘿——我已经审阅了你的更改,整体看起来很棒!

Sourcery 评估

需要人工审阅。 错误的 x-wop-sub-mch-id 可能导致业务请求以错误的二级商户身份上下文运行,并可能在那里创建或修改记录。回滚会移除对该请求头的支持,但无法撤销网关端已经执行的操作。


Sourcery 对开源项目免费——如果你喜欢我们的审阅,请考虑分享 ✨
Original comment in English

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Needs a human reviewer. A mistaken x-wop-sub-mch-id can cause a business request to run in the wrong sub-merchant’s identity context, potentially creating or changing records there. Reverting removes the header support but does not undo any gateway-side actions already taken.


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

@im47cn

im47cn commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

【独立复审 · fork 分支已拉本地实跑(444 用例 + 覆盖率 98.89% + AC-20 跨版本字节对比)】实现通过,合并前须更新 API 快照

实跑验证(worktree @ 0b8b807,pytest 8.4.2):

项 结果
python -m pytest --cov=wop_sdk --cov-branch --cov-fail-under=98 444 collected 全过 exit 0;覆盖率 98.89%(stmt 1243/miss 9;branch 376/partial 9),98% 门禁通过
变更行覆盖 client.py 新增可执行行 22/22 = 100%(lefthook 95% 红线过)
scripts/check-equivalent-anchors.py ok
scripts/check-api-snapshot.py exit 1 失败——漂移正是本 PR 新增面:公共函数 resolve_sub_mch_id、build_request/execute 的 kw-only sub_mch_id、docstring
AC-20 跨版本实测 冻结 timestamp_ms/nonce/request_id/csprng 下,origin/main vs 本 PR 的 L0 有体/无体/L2/自定义头四组请求,headers(含 x-wop-sign)与 wire_body 逐字节相同

逐行核对(对照 wop-specs#28 附录 J):全部吻合——

  • J1:client.py:334-336 头写入在 canonical/sign 之前,sorted(iter(headers)) 自动入签 ✅
  • J2:resolve_sub_mch_id trim 前原值逐字符扫 0x20–0x7E(错误只回 ord(ch) 不回显值)、trim 后空=缺席、内部空格仅查 0x20(与 java 一致无漂移)、>128 拒,全部 ConfigurationError 构造期 ✅
  • 双来源即拒:extra_headers 同名与参数同传拒,且循环对两者 continue 不会二次覆盖 ✅
  • J3:入向 verify_response/verify_callback 未改,无白名单消费 ✅

合并前须办:python3 scripts/check-api-snapshot.py --update 更新 tests/api_snapshot.json 并随 PR 提交,否则 api-snapshot CI job 必红。

2 处文字级(非阻断):

  1. README 中英版「首尾空白 trim 后发送」措辞偏宽——实现是 trim 前原值扫描,带 \t\r\n 的值(含首尾)会构造期被拒,仅 0x20 可 trim。
  2. 工具链既有漂移(非本 PR):CI 未钉 pytest 版本,本机拉到 pytest 9.2.0 时 pytest-bdd 8.x 全炸(FixtureManager._arg2fixturedefs 被删)——已用 origin/main + pytest 9.2.0 复现同样失败,建议仓里把 pytest 钉到 <9。

快照更新后可以合并。

@im47cn

im47cn commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

【独立复审 · fork 分支已拉本地实跑(444 用例 + 覆盖率 98.89% + AC-20 跨版本字节对比)】实现通过,合并前须更新 API 快照

实跑验证(worktree @ 0b8b807,pytest 8.4.2):

项 结果
python -m pytest --cov=wop_sdk --cov-branch --cov-fail-under=98 444 collected 全过 exit 0;覆盖率 98.89%(stmt 1243/miss 9;branch 376/partial 9),98% 门禁通过
变更行覆盖 client.py 新增可执行行 22/22 = 100%(lefthook 95% 红线过)
scripts/check-equivalent-anchors.py ok
scripts/check-api-snapshot.py exit 1 失败——漂移正是本 PR 新增面:公共函数 resolve_sub_mch_id、build_request/execute 的 kw-only sub_mch_id、docstring
AC-20 跨版本实测 冻结 timestamp_ms/nonce/request_id/csprng 下,origin/main vs 本 PR 的 L0 有体/无体/L2/自定义头四组请求,headers(含 x-wop-sign)与 wire_body 逐字节相同

逐行核对(对照 wop-specs#28 附录 J):全部吻合——

  • J1:client.py:334-336 头写入在 canonical/sign 之前,sorted(iter(headers)) 自动入签 ✅
  • J2:resolve_sub_mch_id trim 前原值逐字符扫 0x20–0x7E(错误只回 ord(ch) 不回显值)、trim 后空=缺席、内部空格仅查 0x20(与 java 一致无漂移)、>128 拒,全部 ConfigurationError 构造期 ✅
  • 双来源即拒:extra_headers 同名与参数同传拒,且循环对两者 continue 不会二次覆盖 ✅
  • J3:入向 verify_response/verify_callback 未改,无白名单消费 ✅

合并前须办:python3 scripts/check-api-snapshot.py --update 更新 tests/api_snapshot.json 并随 PR 提交,否则 api-snapshot CI job 必红。

2 处文字级(非阻断):

  1. README 中英版「首尾空白 trim 后发送」措辞偏宽——实现是 trim 前原值扫描,带 \t\r\n 的值(含首尾)会构造期被拒,仅 0x20 可 trim。
  2. 工具链既有漂移(非本 PR):CI 未钉 pytest 版本,本机拉到 pytest 9.2.0 时 pytest-bdd 8.x 全炸(FixtureManager._arg2fixturedefs 被删)——已用 origin/main + pytest 9.2.0 复现同样失败,建议仓里把 pytest 钉到 <9。

快照更新后可以合并。

CI 触发说明:本 PR 为 fork PR,GitHub Actions 测试腿在 PR 上未触发(check rollup 仅 Sourcery/Snyk);上表「必红」均指本地按 ci.yml 同命令复跑 exit=1(同命令在 origin/main exit=0),合入后 push 侧 CI 才会真正执行该门。

- resolve_sub_mch_id 与 extra_headers 取值链增加 isinstance(str) 校验:
  extra_headers={'x-wop-sub-mch-id': None} 此前被 str() 归一为 'None' 并静默入签,
  数值入参则抛裸 TypeError;现统一构造期抛 configuration
- 去掉 extra_headers 侧 str() 强转,原值进同一校验链
- 双来源消歧改为「两侧各自按 J2 解析后再判」:空白参数不再与真实 extra 值误判为同传
- 补测试:execute 入口入签、extra_headers 空白零回归、None/数值/bytes 负例、双来源消歧
im47cn-bot and others added 2 commits October 28, 2026 11:29
api-snapshot 门禁在 0b8b807 起即漂移(新增 build_request/execute 的 sub_mch_id
参数与 docstring 未随 PR 更新基线,该 commit 的 CI 为 action_required 未执行到)。
按 scripts/check-api-snapshot.py --update(griffe==1.14.0)重生成,无其他 API 变更。

Co-Authored-By: Claude <noreply@anthropic.com>
pytest 9.2 移除了 FixtureManager._arg2fixturedefs,pytest-bdd(含最新 9.0.0)仍引用旧名,
不锁版即 21 条 test_bdd.py 全部 AttributeError——与业务代码无关,任何分支今天跑都红。
证据:2026-10-26 最近一次全绿 run 40294534964 装的是 pytest-8.4.2 + pytest-bdd-8.1.0;
今天 run 40679072217 装到 pytest-9.2.0 + pytest-bdd-9.0.0,失败仅限 test_bdd.py(21/21)。
本地按锁定组合复跑:453 passed。

Co-Authored-By: Claude <noreply@anthropic.com>
@im47cn
im47cn merged commit 15a4080 into wop-platform:main Oct 28, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants